• Documentation: Missing documentation PR. This introduces new public API surface (AgentAsTool class, Agent.as_tool() method) and requires user documentation per project guidelines.
• API Review: Consider adding needs-api-review label since this adds new public abstractions customers will use.
• Design Clarification: The preserve_context parameter from [FEATURE] Agent to_tool method #1002 should be addressed - either as part of this PR or explicitly deferred.

• ✅ Documentation PR: Now linked (feat: add section in user guide on new functionality for Agent.as_tool() docs#686)
• ✅ preserve_context parameter: Implemented with proper input schema, context clearing logic, and comprehensive tests
• ✅ Input type handling: Added explicit type checks with warning logs for unexpected input formats
• ✅ Test coverage: Expanded from 213 to 352 lines with tests for all new functionality

• The discussion with @awsarron about class vs @tool approach is still open - waiting for direction on how to proceed
• Coverage at 94.52% is acceptable; the 4 uncovered lines appear to be edge cases
• Previous inline comments about empty string checks remain as suggestions but are not blocking

The lock implementation is correct:

• Non-blocking acquire (line 168): Returns error if agent is busy instead of blocking
• Early return safety: If lock acquire fails, returns before holding the lock (no leak)
• Finally block (line 250-251): Ensures lock is always released, even on exceptions
• Threading.Lock choice: Correct for run_async() which may use separate threads/event loops

1. Sub-agent hits interrupt → returns AgentResult with stop_reason="interrupt"
2. AgentAsTool.stream() yields ToolInterruptEvent (line 216)
3. Executor registers interrupts in parent's _interrupt_state (executor.py:233-234)
4. On resume: _is_sub_agent_interrupted() detects activated state
5. _build_interrupt_responses() packages responses (filtering None values)
6. Sub-agent receives responses instead of original prompt

The Problem

When a sub-agent has a session manager AND preserve_context=False (the default), the in-memory state and persisted state diverge after the first invocation:

sub_agent = Agent(session_manager=FileSessionManager(session_id="s1"))
tool = sub_agent.as_tool()  # preserve_context=False (default)
parent = Agent(tools=[tool])

What Happens

Invocation 1:

1. _reset_agent_state(): agent.messages = deepcopy([]) (direct list assignment)
2. stream_async() runs → _append_messages() fires MessageAddedEvent
3. Session hooks fire: append_message(A, idx=0), append_message(B, idx=1), append_message(C, idx=2)
4. AfterInvocationEvent → sync_agent() persists state
5. Session file: [A(0), B(1), C(2)] ✅
6. In-memory: [A, B, C] ✅

Invocation 2:

1. _reset_agent_state(): agent.messages = deepcopy([]) — but session._latest_agent_message still points to C(idx=2)
2. stream_async() runs → _append_messages() fires MessageAddedEvent
3. Session hooks fire: append_message(D, idx=3), append_message(E, idx=4) — indices continue from previous
4. Session file: [A(0), B(1), C(2), D(3), E(4)] — accumulating ❌
5. In-memory: [D, E] — amnesiac, as intended ✅

Root Cause

_reset_agent_state() does a direct list assignment (self._agent.messages = copy.deepcopy(...)) which bypasses _append_messages() and therefore never fires MessageAddedEvent. The session manager:

1. Never sees the reset happen
2. Never prunes old messages
3. Keeps its _latest_agent_message tracker pointing to the last message from the previous invocation
4. Continues appending new messages at ever-increasing indices

Consequence

If the sub-agent is ever restored from session (e.g., process restart, rehydration), it gets ALL accumulated messages [A, B, C, D, E], defeating the amnesiac intention entirely.

Additional Nuance: "Amnesiac" Doesn't Mean "Empty"

The snapshot is taken after Agent.__init__() fires AgentInitializedEvent, which triggers the session manager's initialize() method. If there's a persisted session, messages are restored into agent.messages before the snapshot. So _initial_messages = whatever the session manager restored, not [].

preserve_context=False really means "reset to session-restored state", not "reset to empty".

Note

The GraphNode.reset_executor_state() pattern (which this mirrors) has the same potential issue — it's just less visible because graph nodes are typically short-lived and don't persist across process restarts.

Is There a Race Condition?

No, in the traditional sense. The threading.Lock in AgentAsTool.stream() ensures _reset_agent_state() + stream_async() happen atomically. A concurrent caller gets an immediate error.

But There IS a Stale State Issue

After _reset_agent_state():

• agent.messages = [] ✅
• agent.state = initial_state ✅
• session._latest_agent_message[agent_id] = SessionMessage(message_id=N) from previous invocation ❌ (not reset)
• agent.conversation_manager state (e.g., removed_message_count) = stale from previous invocations ❌ (not reset)

The session manager's internal trackers are not aware of the agent reset. They continue operating as if the conversation is continuous.

_reset_agent_state only resets:

• ✅ agent.messages
• ✅ agent.state

_reset_agent_state does NOT reset:

• ❌ session_manager._latest_agent_message
• ❌ agent.conversation_manager state
• ❌ agent._interrupt_state (but this is handled separately via _is_sub_agent_interrupted)

The Constraint

preserve_context defaults to False. But preserve_context=False requires an Agent instance (not AgentBase). This means:

Is This Actually a Problem?

Not really. The as_tool() convenience method only exists on Agent, so the default preserve_context=False always has a valid target. A2A agents can't accidentally hit this because they'd have to go through AgentAsTool(...) directly, which raises a clear TypeError.

The error message is explicit:

TypeError: preserve_context=False requires an Agent instance, got MyCustomAgent

Why This Design?

AgentBase doesn't guarantee messages or state attributes exist. You can't snapshot/restore what doesn't exist. So the type check is correct — it's a capability check, not an arbitrary restriction.

TestPreserveContextWithSessionManager::test_reset_does_not_trigger_message_added_hooks PASSED
TestPreserveContextWithSessionManager::test_session_manager_initialize_runs_on_sub_agent_construction PASSED
TestPreserveContextWithSessionManager::test_session_message_index_diverges_after_reset PASSED
TestPreserveContextWithSessionManager::test_sync_agent_after_reset_persists_wrong_state PASSED
TestRaceConditions::test_reset_then_stream_is_not_atomic_with_session_hooks PASSED
TestRaceConditions::test_session_latest_message_not_reset PASSED
TestPreserveContextDefault::test_default_raises_for_agent_base PASSED
TestPreserveContextDefault::test_preserve_context_true_works_for_agent_base PASSED
TestPreserveContextDefault::test_default_means_a2a_agents_must_use_preserve_context_true PASSED
TestFundamentalIssue::test_document_the_divergence_scenario PASSED
TestFundamentalIssue::test_verify_session_hooks_registered_on_sub_agent PASSED
TestConversationManagerInteraction::test_conversation_manager_state_not_reset PASSED
TestConversationManagerInteraction::test_apply_management_runs_after_each_invocation PASSED

Tests verify code structure and behavior via source inspection + runtime type checking. No mocked model calls needed — these test the interaction patterns, not the end-to-end flow.

For This PR

1. Document the session manager interaction in the docstring — Add a note to preserve_context parameter docs that it does NOT coordinate with session managers. Developers who set both will get in-memory amnesiac but persistent accumulation.

2. Consider a warning — When preserve_context=False and the wrapped agent has a _session_manager, log a warning:

   if not preserve_context and hasattr(agent, '_session_manager') and agent._session_manager:
       logger.warning("preserve_context=False with a session manager may cause state divergence")

For Future Work

3. Unified state management — Both GraphNode.reset_executor_state() and AgentAsTool._reset_agent_state() have the same pattern and same gap. This should move to a first-class method on Agent (e.g., agent.reset_to_snapshot(snapshot)) that properly coordinates with session managers and conversation managers.

4. Session-aware reset — The reset method should either:

   • Clear session messages and reset the _latest_agent_message tracker, OR
   • Detach the session manager during sub-agent tool invocations (the sub-agent's session is the parent's concern, not its own)

Cross-Framework Analysis

I went through the actual source code of Google ADK, OpenAI Agents SDK, CrewAI, and LangGraph to understand how they handle context/message history in agent-as-tool patterns.

Summary Table

Key Finding: Strands Is Unique in HOW It Achieves Isolation

Every other SDK achieves isolation by creating fresh infrastructure around the agent (new runner, new session, new task). Strands achieves it by mutating the agent directly (agent.messages = deepcopy(...)).

This is why preserve_context=False has the session manager divergence bug — the reset bypasses the agent's own state management components.

What Other SDKs Do

• Google ADK (AgentTool): Creates InMemorySessionService() and a brand new session for every invocation. State deltas forwarded back via tool_context.state.update(). Transfer/handoff pattern shares context (different mechanism).

• OpenAI Agents SDK (agent.as_tool()): Creates a fresh Runner.run() call. Docstring: "In handoffs, the new agent receives the conversation history. In this tool, the new agent receives generated input." Supports explicit session/conversation_id params for opt-in persistence.

• CrewAI (DelegateWorkTool): Creates a new Task() per delegation. Context is an explicit string parameter, never accumulated conversation history.

• LangGraph: Each subgraph has its own StateGraph with independent messages state. No shared state between parent/child unless explicitly mapped.

The Tension

All SDKs agree: agent-as-tool should default to fresh/isolated context.

But Strands has a unique challenge: when developers construct an Agent with specific components (session managers, conversation managers) and pass it as a tool, preserve_context=False bypasses those components entirely. No other SDK has this problem because they don't mutate the agent.

Recommendation

Three options discussed in the detailed analysis:

1. Make preserve_context required (no default) — forces explicit choice, collects usage data
2. Default to True — least destructive, respects agent components, works with AgentBase
3. Default to False (current) — industry-consistent, but broken with session managers

Long-term: the isolation mechanism should follow the ADK/OpenAI pattern (fresh execution context around the agent) rather than mutating the agent directly.

• ✅ Session manager check (lines 89-95): ValueError raised when preserve_context=False with session manager
• ✅ Description handling: Moved to constructor with proper fallback (line 75-77)
• ✅ Type annotation: agent: Agent is explicit about requirements

@mkmeral raised a valid point: should _AgentAsTool be:

1. Truly private — Remove from __all__, customers only use agent.as_tool()
2. Public — Rename to AgentAsTool, export properly

The current state (private name + public export) is contradictory. I'd suggest option 1 (truly private) since customers have agent.as_tool() as the main API.

API Design:

• _AgentAsTool is truly private (underscore prefix, not exported)
• Public API as_tool() returns AgentTool (public base type)
• Docstrings don't reference internal implementation details

Key Features:

• preserve_context parameter (default False for stateless invocations)
• Session manager check raises ValueError when incompatible
• Concurrency protection with threading.Lock
• Interrupt propagation to parent agent
• AgentAsToolStreamEvent for differentiating sub-agent events

Test Coverage: 97.20% with 676 lines of comprehensive tests